
/*
 * Copyright 2002-2022 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/*
 *版权所有2002-2022原作者。
 *
 *根据Apache许可证2.0版许可（“许可证”）；
 *除非符合许可证的规定，否则您不得使用此文件。
 *您可以在以下网址获取许可证副本：
 *
 *https://www.apache.org/licenses/LICENSE-2.0
 *
 *除非适用法律要求或书面同意，软件
 *根据许可证进行的分发是在“按原样”的基础上进行的，
 *无任何明示或暗示的保证或条件。
 *有关管理权限的特定语言，请参阅许可证和
 *许可证下的限制。
 */

package org.springframework.validation;

import java.beans.PropertyEditor;
import java.util.Map;

import org.springframework.beans.PropertyEditorRegistry;
import org.springframework.lang.Nullable;

/**
 * General interface that represents binding results. Extends the
 * {@link Errors} interface for error registration capabilities,
 * allowing for a {@link Validator} to be applied, and adds
 * binding-specific analysis and model building.
 *
 * <p>Serves as result holder for a {@link DataBinder}, obtained via
 * the {@link DataBinder#getBindingResult()} method. BindingResult
 * implementations can also be used directly, for example to invoke
 * a {@link Validator} on it (e.g. as part of a unit test).
 *
 * @author Juergen Hoeller
 * @since 2.0
 * @see DataBinder
 * @see Errors
 * @see Validator
 * @see BeanPropertyBindingResult
 * @see DirectFieldBindingResult
 * @see MapBindingResult
 */
/**
 *表示绑定结果的通用接口。扩展
 *｛@link Errors｝接口用于错误注册功能，
 *允许应用｛@link Validator｝，并添加
 *结合具体分析和模型构建。
 *
 *<p>作为｛@link DataBinder｝的结果持有者，通过
 *｛@link DataBinder#getBindingResult（）｝方法。绑定结果
 *实现也可以直接使用，例如调用
 *上面有一个{@link Validator}（例如，作为单元测试的一部分）。
 *
 *@作者于尔根·霍勒
 *@自2.0起
 *@参见DataBinder
 *@查看错误
 *@see验证器
 *@see BeanProperty绑定结果
 *@请参阅DirectFieldBindingResult
 *@参见MapBindingResult
 */
public interface BindingResult extends Errors {

	/**
	 * Prefix for the name of the BindingResult instance in a model,
	 * followed by the object name.
	 */
	/**
	 *模型中BindingResult实例名称的前缀，
	 *后面跟着对象名称。
	 */
	String MODEL_KEY_PREFIX = BindingResult.class.getName() + ".";


	/**
	 * Return the wrapped target object, which may be a bean, an object with
	 * public fields, a Map - depending on the concrete binding strategy.
	 */
	/**
	 *返回包装后的目标对象，它可能是一个bean，一个具有
	 *公共领域，地图-取决于具体的绑定策略。
	 */
	@Nullable
	Object getTarget();

	/**
	 * Return a model Map for the obtained state, exposing a BindingResult
	 * instance as '{@link #MODEL_KEY_PREFIX MODEL_KEY_PREFIX} + objectName'
	 * and the object itself as 'objectName'.
	 * <p>Note that the Map is constructed every time you're calling this method.
	 * Adding things to the map and then re-calling this method will not work.
	 * <p>The attributes in the model Map returned by this method are usually
	 * included in the {@link org.springframework.web.servlet.ModelAndView}
	 * for a form view that uses Spring's {@code bind} tag in a JSP,
	 * which needs access to the BindingResult instance. Spring's pre-built
	 * form controllers will do this for you when rendering a form view.
	 * When building the ModelAndView instance yourself, you need to include
	 * the attributes from the model Map returned by this method.
	 * @see #getObjectName()
	 * @see #MODEL_KEY_PREFIX
	 * @see org.springframework.web.servlet.ModelAndView
	 * @see org.springframework.web.servlet.tags.BindTag
	 */
	/**
	 *返回所获得状态的模型映射，公开BindingResult
	 *实例为“｛@link#MODEL_KEY_PREFIX MODEL_KEY_PREFIX｝+objectName”
	 *而对象本身为“objectName”。
	 *<p>请注意，每次调用此方法时都会构造Map。
	 *向映射中添加内容，然后重新调用此方法将不起作用。
	 *<p>此方法返回的模型Map中的属性通常为
	 *包含在{@linkorg.springframework.web.servlet.ModelAndView}中
	 *对于在JSP中使用Spring的{@code-bind}标记的表单视图，
	 *其需要访问BindingResult实例。Spring的预制
	 *表单控制器将在呈现表单视图时为您执行此操作。
	 *当您自己构建ModelAndView实例时，需要包括
	 *此方法返回的模型Map中的属性。
	 *@参见#getObjectName（）
	 *@参见#MODEL_KEY_PREFIX
	 *@参见org.springframework.web.servlet.ModelAndView
	 *@参见org.springframework.web.servlet.tags.BindTag
	 */
	Map<String, Object> getModel();

	/**
	 * Extract the raw field value for the given field.
	 * Typically used for comparison purposes.
	 * @param field the field to check
	 * @return the current value of the field in its raw form, or {@code null} if not known
	 */
	/**
	 *提取给定字段的原始字段值。
	 *通常用于比较目的。
	 *@param字段要检查的字段
	 *@以原始形式返回字段的当前值，或者｛@code null｝（如果未知）
	 */
	@Nullable
	Object getRawFieldValue(String field);

	/**
	 * Find a custom property editor for the given type and property.
	 * @param field the path of the property (name or nested path), or
	 * {@code null} if looking for an editor for all properties of the given type
	 * @param valueType the type of the property (can be {@code null} if a property
	 * is given but should be specified in any case for consistency checking)
	 * @return the registered editor, or {@code null} if none
	 */
	/**
	 *为给定的类型和属性查找自定义属性编辑器。
	 *@param字段属性的路径（名称或嵌套路径），或
	 *｛@code null｝如果正在为给定类型的所有属性寻找编辑器
	 *@param value键入属性的类型（如果是属性，则可以为｛@code null｝
	 *已给出，但在任何情况下都应指定以进行一致性检查）
	 *@返回注册的编辑器，或者｛@code null｝如果没有
	 */
	@Nullable
	PropertyEditor findEditor(@Nullable String field, @Nullable Class<?> valueType);

	/**
	 * Return the underlying PropertyEditorRegistry.
	 * @return the PropertyEditorRegistry, or {@code null} if none
	 * available for this BindingResult
	 */
	/**
	 *返回基础PropertyEditorRegistry。
	 *@return PropertyEditorRegistry，或者｛@code null｝如果没有
	 *可用于此BindingResult
	 */
	@Nullable
	PropertyEditorRegistry getPropertyEditorRegistry();

	/**
	 * Resolve the given error code into message codes.
	 * <p>Calls the configured {@link MessageCodesResolver} with appropriate parameters.
	 * @param errorCode the error code to resolve into message codes
	 * @return the resolved message codes
	 */
	/**
	 *将给定的错误代码解析为消息代码。
	 *<p>使用适当的参数调用已配置的｛@link MessageCodesResolver｝。
	 *@param errorCode将要解析的错误代码编码为消息代码
	 *@返回解析后的消息代码
	 */
	String[] resolveMessageCodes(String errorCode);

	/**
	 * Resolve the given error code into message codes for the given field.
	 * <p>Calls the configured {@link MessageCodesResolver} with appropriate parameters.
	 * @param errorCode the error code to resolve into message codes
	 * @param field the field to resolve message codes for
	 * @return the resolved message codes
	 */
	/**
	 *将给定的错误代码解析为给定字段的消息代码。
	 *<p>使用适当的参数调用已配置的｛@link MessageCodesResolver｝。
	 *@param errorCode将要解析的错误代码编码为消息代码
	 *@param字段用于解析消息代码的字段
	 *@返回解析后的消息代码
	 */
	String[] resolveMessageCodes(String errorCode, String field);

	/**
	 * Add a custom {@link ObjectError} or {@link FieldError} to the errors list.
	 * <p>Intended to be used by cooperating strategies such as {@link BindingErrorProcessor}.
	 * @see ObjectError
	 * @see FieldError
	 * @see BindingErrorProcessor
	 */
	/**
	 *将自定义{@link ObjectError}或{@link FieldError}添加到错误列表中。
	 *<p>旨在由合作策略使用，如{@link BindingErrorProcessor}。
	 *@见ObjectError
	 *@参见字段错误
	 *@请参阅BindingErrorProcessor
	 */
	void addError(ObjectError error);

	/**
	 * Record the given value for the specified field.
	 * <p>To be used when a target object cannot be constructed, making
	 * the original field values available through {@link #getFieldValue}.
	 * In case of a registered error, the rejected value will be exposed
	 * for each affected field.
	 * @param field the field to record the value for
	 * @param type the type of the field
	 * @param value the original value
	 * @since 5.0.4
	 */
	/**
	 *记录指定字段的给定值。
	 *<p>当无法构建目标对象时使用，使
	 *通过{@link#getFieldValue}可用的原始字段值。
	 *在注册错误的情况下，将暴露被拒绝的值
	 *对于每个受影响的字段。
	 *@param字段要记录其值的字段
	 *@param type字段的类型
	 *@param value原始值
	 *@自5.0.4起
	 */
	default void recordFieldValue(String field, Class<?> type, @Nullable Object value) {
	}

	/**
	 * Mark the specified disallowed field as suppressed.
	 * <p>The data binder invokes this for each field value that was
	 * detected to target a disallowed field.
	 * @see DataBinder#setAllowedFields
	 */
	/**
	 *将指定的不允许的字段标记为禁止显示。
	 *<p>数据绑定器为
	 *检测到以不允许的字段为目标。
	 *@参见DataBinder#setAllowedFields
	 */
	default void recordSuppressedField(String field) {
	}

	/**
	 * Return the list of fields that were suppressed during the bind process.
	 * <p>Can be used to determine whether any field values were targeting
	 * disallowed fields.
	 * @see DataBinder#setAllowedFields
	 */
	/**
	 *返回在绑定过程中被抑制的字段的列表。
	 *<p>可用于确定是否有任何字段值作为目标
	 *不允许的字段。
	 *@参见DataBinder#setAllowedFields
	 */
	default String[] getSuppressedFields() {
		return new String[0];
	}

}
